00. 사전 준비: Docker Desktop 설치부터 3노드 Kubernetes · istioctl 구축까지

전체 구축 순서 한눈에 보기

1. PC 권장 사양 및 터미널 선택

1-1. 하드웨어 권장 사양

본 스터디는 쿠버네티스 노드 3대 + Istio 서비스 메시 + 외부 PostgreSQL VM + LGTM(Loki·Grafana·Tempo·Mimir/VictoriaMetrics) 관측 스택을 로컬에서 직접 띄우므로 아래 사양을 권장합니다.

1-2. 사용할 터미널: Windows는 반드시 PowerShell

2. Docker Hub 계정 만들기 (무료)

Docker Hub는 컨테이너 이미지(istio/proxyv2, grafana/alloy, postgres 등)를 내려받는 공식 저장소입니다.

1. https://hub.docker.com 에 접속해 Sign up으로 무료(Personal) 계정을 만듭니다.
2. 왜 로그인이 필요한가요?
   • 비로그인 상태에서는 같은 공인 IP 기준 6시간당 100회까지만 이미지를 내려받을 수 있습니다.
   • 서비스 메시와 LGTM 모니터링 스택은 여러 개의 컨테이너 이미지를 한꺼번에 받아오므로, Docker Desktop에 로그인해 두어야 다운로드 한도 초과(429 Too Many Requests: toomanyrequests) 에러를 겪지 않습니다.

3. WSL 2 및 Docker Desktop 설치

3-1. Windows: WSL 2 설치 및 최신화

1. 시작 메뉴에서 PowerShell을 찾아 우클릭 → 관리자 권한으로 실행을 누릅니다.
2. 아래 명령어를 순서대로 실행해 WSL 2를 설치하고 최신 커널로 업데이트합니다.

# 1. WSL 기본 기능 활성화 (이미 설치되어 있으면 안내 메시지만 출력됨)
wsl --install --no-distribution

# 2. WSL 커널을 최신 버전으로 업데이트
wsl --update

# 3. 설치된 WSL 버전 확인 (WSL 버전 2.x 이상, 커널 6.6 이상이면 정상)
wsl --version

출력 예시:

WSL 버전: 2.6.3.0
커널 버전: 6.6.87.2-1
WSLg 버전: 1.0.71
...

3-2. Docker Desktop 다운로드 및 설치

방법 A. 설치 파일 다운로드 (권장)

1. https://docs.docker.com/desktop/setup/install/windows-install/ 에 접속해 Docker Desktop for Windows - x86_64 설치 파일을 내려받습니다. (macOS 사용자는 Mac 칩에 맞춰 Apple Silicon 또는 Intel 버전을 받습니다.)
2. Docker Desktop Installer.exe를 실행합니다.
3. 설치 옵션 화면에서 Use WSL 2 instead of Hyper-V (recommended) 가 체크된 상태(기본값)로 OK를 눌러 설치합니다.

방법 B. PowerShell에서 winget으로 한 줄 설치 (Windows)

winget install -e --id Docker.DockerDesktop

3-3. Docker Desktop 실행 및 로그인

1. 설치가 끝나면 시작 메뉴에서 Docker Desktop을 실행합니다.
2. 약관 동의 화면에서 Accept를 누릅니다.
3. 창 왼쪽 아래 상태 표시줄에 초록색 점과 함께 Engine running 이 뜨는지 확인합니다.
4. 우측 상단의 Sign in 버튼을 눌러 2단계에서 만든 Docker Hub 계정으로 로그인합니다.

PowerShell(일반 권한 창)을 열고 엔진이 잘 응답하는지 확인합니다.

docker version

출력 예시: Client와 Server: Docker Desktop이 모두 출력되면 성공입니다.

Client:
 Version:           29.1.3
...
Server: Docker Desktop 4.56.0 (214940)
 Engine:
  Version:          29.1.3

4. Kubernetes 3노드 클러스터 구축 (kind 방식)

이제 컨테이너들을 지휘할 3노드 Kubernetes 클러스터(관리 본부 control-plane 1대 + 일꾼 worker 2대) 를 띄웁니다.

클러스터를 만드는 방법은 [방법 A: Docker Desktop UI 내장 kind 기능 사용] 과 [방법 B: kind CLI로 직접 생성] 두 가지가 있으며, 원리는 100% 동일합니다.

4-1. [방법 A] Docker Desktop 내장 Kubernetes 기능으로 3노드 만들기 (UI 방식)

Docker Desktop 최신 버전(4.38 이상)에는 클릭 몇 번으로 멀티 노드 클러스터를 만들어 주는 kind 프로비저너가 내장되어 있습니다. (단, Docker Desktop에 로그인(Sign in) 되어 있어야 kind 옵션을 선택할 수 있습니다.)

1. Docker Desktop 오른쪽 위 톱니바퀴 아이콘(Settings ⚙️) 을 누릅니다.
2. 왼쪽 메뉴에서 Kubernetes 탭을 클릭합니다.
3. Enable Kubernetes 토글을 켭니다.
4. Cluster provisioning method (클러스터 생성 방식) 에서 기본값인 kubeadm 대신 반드시 kind 를 선택합니다!
   • Number of nodes (노드 개수): 슬라이더를 움직여 3 으로 맞춥니다.
   • Kubernetes version: 최신 버전(기본값)을 그대로 둡니다.
5. 오른쪽 아래 Apply & restart 버튼을 누르고 1~2분 정도 기다립니다.
6. 왼쪽 아래에 초록색 점으로 Kubernetes running 이 표시되면 완료입니다!

4-2. [참고 대안] 독립 kind CLI로 별도 클러스터를 직접 생성하는 방법

Docker Desktop UI의 내장 Kubernetes가 버전 제한이나 Starting... 무한 대기 문제를 일으킬 때, 쿠버네티스 공식 kind 바이너리를 내려받아 명령어로 3노드 클러스터를 띄우는 방법입니다. (Docker Desktop 내장 kind 모드와 100% 똑같은 구조로 동작하며, 원하는 최신 K8s 버전을 즉시 쓸 수 있고 실습 후 초기화도 3초면 끝납니다.)

PowerShell에 아래 명령어를 복사해 실행합니다.

# 1. 내 사용자 폴더 아래 전용 도구 폴더($HOME\bin) 생성 및 Path 환경 변수 등록
New-Item -ItemType Directory -Path "$HOME\bin" -Force | Out-Null
$env:Path += ";$HOME\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ($userPath -notlike "*$HOME\bin*") {
    [Environment]::SetEnvironmentVariable("Path", "$userPath;$HOME\bin", "User")
}

# 2. kind v0.33.0 (최신 안정 버전) 다운로드
curl.exe -sSLo "$HOME\bin\kind.exe" "https://github.com/kubernetes-sigs/kind/releases/download/v0.33.0/kind-windows-amd64"
kind version

출력 예시:

kind v0.33.0 go1.26.1 windows/amd64

이제 실습 폴더($HOME\mesh-study)를 만들고, 컨트롤 플레인 1대 + 워커 노드 2대(총 3노드) 설계도를 작성해 클러스터를 생성합니다.

mkdir "$HOME\mesh-study" -Force | Out-Null
cd "$HOME\mesh-study"

@"
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: mesh-lab
nodes:
  - role: control-plane
  - role: worker
  - role: worker
"@ | Set-Content -Path kind-config.yaml -Encoding utf8

kind create cluster --config kind-config.yaml

출력 예시:

Creating cluster "mesh-lab" ...
 ✓ Ensuring node image (kindest/node:v1.37.0) 🖼
 ✓ Preparing nodes 📦 📦 📦
 ✓ Writing configuration 📜
 ✓ Starting control-plane 🕹️
 ✓ Installing CNI 🔌
 ✓ Installing StorageClass 💾
 ✓ Joining worker nodes 🚜
Set kubectl context to "kind-mesh-lab"

5. istioctl 및 Helm 설치

Docker Desktop을 설치하면 쿠버네티스 기본 명령줄 도구인 kubectl은 이미 자동으로 함께 설치되어 있습니다 (C:\Program Files\Docker\Docker\resources\bin\kubectl.exe).

여기에 서비스 메시(Istio) 전용 제어 도구인 istioctl 과, 후반부 LGTM 모니터링 스택(Grafana Alloy, Loki, Tempo, Mimir/VictoriaMetrics)을 한 방에 설치할 쿠버네티스용 앱스토어 도구인 Helm 두 가지를 추가로 설치합니다.

5-1. istioctl 1.31.3 설치

curl.exe -sSLo "$HOME\bin\istioctl.zip" "https://github.com/istio/istio/releases/download/1.31.3/istioctl-1.31.3-win.zip"
Expand-Archive -Path "$HOME\bin\istioctl.zip" -DestinationPath "$HOME\bin" -Force
Remove-Item "$HOME\bin\istioctl.zip"
istioctl version --remote=false

출력 예시:

client version: 1.31.3

5-2. Helm (쿠버네티스 패키지 매니저) 확인 및 설치

이미 helm이 설치되어 있는지 확인하고, 없다면 winget 또는 바이너리로 설치합니다.

# helm 설치 여부 확인 (버전이 출력되면 이미 설치된 것임)
helm version --short

만약 helm 명령어를 찾을 수 없다고 나오면 아래 명령어로 즉시 설치합니다.

winget install -e --id Helm.Helm

5-3. Terraform (Part 07 IaC 실습용) 확인 및 설치

Part 07에서 하이브리드 서비스 메시 리소스를 코드로 관리(IaC)할 때 사용하는 Terraform도 함께 확인하고, 없다면 $HOME\bin에 바로 내려받아 둡니다.

# terraform 설치 여부 확인 및 미설치 시 $HOME\bin에 자동 설치
if (-not (Get-Command terraform -ErrorAction SilentlyContinue)) {
    curl.exe -sSLo "$HOME\bin\terraform.zip" "https://releases.hashicorp.com/terraform/1.11.0/terraform_1.11.0_windows_amd64.zip"
    Expand-Archive -Path "$HOME\bin\terraform.zip" -DestinationPath "$HOME\bin" -Force
    Remove-Item "$HOME\bin\terraform.zip"
}
terraform version

6. 최종 상태 점검

아래 명령어를 실행해 Docker Desktop 내장 3노드 클러스터(docker-desktop)와 도구들이 모두 준비되었는지 확인합니다.

# 1. 현재 kubectl이 바라보는 클러스터 확인 (docker-desktop)
kubectl config current-context

# 2. 3개의 노드가 모두 Ready 상태인지 확인
kubectl get nodes -o wide

# 3. 실습용 작업 폴더($HOME\mesh-study) 생성
mkdir "$HOME\mesh-study" -Force | Out-Null

출력 예시 (Docker Desktop 내장 3노드 kind 방식 기준):

docker-desktop

NAME                    STATUS   ROLES           AGE   VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE                         KERNEL-VERSION                     CONTAINER-RUNTIME
desktop-control-plane   Ready    control-plane   3m    v1.31.1   172.19.0.2    <none>        Debian GNU/Linux 12 (bookworm)   6.6.87.2-microsoft-standard-WSL2   containerd://1.7.18
desktop-worker          Ready    <none>          3m    v1.31.1   172.19.0.3    <none>        Debian GNU/Linux 12 (bookworm)   6.6.87.2-microsoft-standard-WSL2   containerd://1.7.18
desktop-worker2         Ready    <none>          3m    v1.31.1   172.19.0.4    <none>        Debian GNU/Linux 12 (bookworm)   6.6.87.2-microsoft-standard-WSL2   containerd://1.7.18

네비게이션